<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <title>jQuery::planize, a plugin to enhance your hierarchical documents</title>
  <style type="text/css">
  html { background: #eee; }
  body { font-size: 13px; font-family: Helvetica, sans; width: 950px; margin: 0 auto; padding: 1em; border-left: 10px solid #ddd; border-right: 10px solid #ddd; background: #fff; }
  blockquote { background: #eee; padding: .2em 1em; border: 1px solid #ccc; }
  blockquote p { padding: 0; margin: .8em 0; }
  code { font-family: Monaco, monospace; font-size: 92%; color: green; background: #eee; padding: 0 .1em; }
  dl { line-height: 1.5em; padding-left: 1.75em; }
  dt { font-weight: bold; font-family: Georgia, serif; font-style: italic; font-size: 105%; color: #336; }
  dd { margin-bottom: .5em; padding: .5em 0; }
  h1 { color: #353; font-family: Helvetica, sans; font-size: 42px; letter-spacing: -3px; margin-top: 0; }
  h2 { color: #557; }
  h3 { color: #757; }
  p { padding-left: 1.75em; line-height: 1.7em; }
  li { line-height: 1.5em; }
  pre { font-family: Monaco, monospace; padding: .5em; margin-left: 1.75em; background: #111; border-left: 5px solid green; color: #fff; font-size: .9em;}
  a.bkl { display: block; width: 200px; padding: .2em; margin: 0 auto; background: #fafafa; color: red; text-decoration: none; font-weight: bold; text-align: center; border: 2px solid red; font-size: 1.2em; text-decoration: underline; }
  div#toc { float: right; width: 30%; margin-left: 1em; padding: .5em; background: #ffe; border: 1px solid #ccc; }
  div#toc h4 { padding: 0; margin: 0; font-size: 1.2em; color: #555; }
  div#toc a { color: black; }
  div#toc ul { list-style-type: none; margin-left: 1em; padding-left: 0; line-height: 1.5em; }
  p#footer { margin: 1em 0 0 0; padding: 0; text-align: center; }
  </style>
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js"></script>
  <script type="text/javascript" src="jquery.planize.js"></script>
  <script type="text/javascript">
  var originalBodyContent;
  function restoreBodyContent(include_toc) {
    $('body').html(originalBodyContent);
    if (include_toc) {
      $('body').prepend('<div id="toc"></div>');
    }
  }
  $(document).ready(function(){
    originalBodyContent = $('body').html();
  });
  </script>
</head>
<body>
  <h1><em>jQPlanize</em> plugin for jQuery</h1>
  <p><strong>The planize <a href="http://jquery.com/" rel="nofollow">jQuery</a> plugin adds some hierarchical data organization features to given DOM node containing HTML headings (you know, the <code>h1 .. h6</code> tags).</strong></p>
  <ul>
    <li>adds numerotation and anchors in front of all headers </li>
    <li>generates an HTML table of content </li>
    <li>degrades gracefully if javascript is not available/enabled </li>
  </ul>
  <p>As an example, how is hard to browse this long page without a table of content? Now click <input type="button" value="this button" onclick="restoreBodyContent(true);$('html *').planize({ number_suffix: '.', generate_toc: true, min_level: 2, toc_elem: $('#toc') });" />. Now, you see?</p>
  <p>The <a href="http://code.google.com/p/jqplanize/">source code</a> and <a href="http://code.google.com/p/jqplanize/issues/list">an issue tracker</a> are hosted at Google.</p>
  
  <h2>See it in action!</h2>
  <p>The examples below will run on the current page HTML source code. At any time you can <input type="button" value="reset the page" onclick="restoreBodyContent()">.</p>
  
  <h3>Headings enumeration for the whole document</h3>
  <pre id="ex1">$('html *').planize();</pre>
  <p><input type="button" value="Run example" onclick="restoreBodyContent();eval($('#ex1').html());return false;" /></p>
  
  <h3>Headings enumeration starting from <code>H2</code></h3>
  <pre id="ex2">$('html *').planize({ min_level: 2 });</pre>
  <p><input type="button" value="Run example" onclick="restoreBodyContent();eval($('#ex2').html());return false;" /></p>
  
  <h3>Headings enumeration starting from <code>H2</code>, with a custom number suffix</h3>
  <pre id="ex2b">$('html *').planize({ min_level: 2, number_suffix: ')' });</pre>
  <p><input type="button" value="Run example" onclick="restoreBodyContent();eval($('#ex2b').html());return false;" /></p>
  
  <h3>Headings enumeration starting from <code>H2</code> headings and Table of Contents generation</h3>
  <pre id="ex3">$('html *').planize({ min_level: 2, generate_toc: true, toc_elem: $('#toc') });</pre>
  <p><input type="button" value="Run example" onclick="restoreBodyContent(true);eval($('#ex3').html());return false;" /></p>
  
  <h3><code>H2</code> headings enumeration only, and Table of Contents generation</h3>
  <pre id="ex4">$('html *').planize({ min_level: 2, max_level: 2, generate_toc: true, toc_elem: $('#toc') });</pre>
  <p><input type="button" value="Run example" onclick="restoreBodyContent(true);eval($('#ex4').html());return false;" /></p>

  <h2>Installation instructions</h2>
  <p>Installation is fairly simple. Just add these lines within the <code>&lt;head&gt;</code> tag of your HTML document: </p>
  <pre>
&lt;script type=&quot;text/javascript&quot; src=&quot;http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;http://jqplanize.googlecode.com/svn/trunk/jquery.planize.js&quot;&gt;&lt;/script&gt;
</pre>
  <p>Note: Maybe storing your own local copy of the <code>jquery.planize.js</code> would be a great idea. </p>
  
  <h2>Basic usage</h2>
  <p>This is a jQuery plugin, so you can apply a custom method to a DOM element or a collection of DOM elements matching a <a href="http://docs.jquery.com/Selectors">jQuery selector</a> call:</p>
  <pre>
$('#myDiv').planize();        // Will match the div with the "myDiv" id in the page
$('div.pageblock').planize(); // Will match all divs with class "pageblocks"
etc.
</pre>
  <p>Configuring jqplanize is done by passing a Javascript object to the <code>planize()</code> function:</p>
  <pre>
$('#myDiv').planize({ generate_toc: true });
</pre>
  <p>Here are the available configuration object parameters:</p>
  <dl>
    <dt>add_anchors</dt>
    <dd>generates anchors for each header (automatically set to true if <code>generate_toc</code> is set to true)</dd>
    <dt>callback</dt>
    <dd>a function called when processing is finished. The <code>toc_elem</code> object will be passed back as an argument.</dd>
    <dt>debug</dt>
    <dd>prints pretty debug messages into the firebug or opera console, if available</dd>
    <dt>generate_toc</dt>
    <dd>generates an html unordered list containing the table of content of the document</dd>
    <dt>min_level</dt>
    <dd>min heading level needed to be included in toc and be renumbered (0 = all headings)</dd>
    <dt>max_level</dt>
    <dd>max heading level needed to be included in toc and be renumbered (0 = all headings)</dd>
    <dt>number_suffix</dt>
    <dd>heading identifier suffix, eg. <code>)</code> in <code>1.2.3)</code></dd>
    <dt>number_separator</dt>
    <dd>separator for numbers, eg. <code>.</code> in <code>1.2.3)</code></dd>
    <dt>toc_elem</dt>
    <dd>the dom element where the toc will be append</dd>
    <dt>toc_none</dt>
    <dd>the message to display if no headings have been found in the current document</dd>
    <dt>toc_title</dt>
    <dd>the title of the table of content</dd>
  </dl>  
  
  <h2>Known issues</h2>
  <ul>
    <li>Currently jqplanize doesn't work in Opera. I'm digging to find out why. </li>
  </ul>

  <h2>The bookmarklet</h2>
  <p>You can drag the bookmarklet below to your personal bookmark bar, so you'll be able to generate the table of content on (quite) every page you browse on the web:</p>
  <p><a href="javascript:var%20s=document.createElement('script');s.setAttribute('src','http://prendreuncafe.com/work/jqplanize/bookmarklet.js');document.getElementsByTagName('head')[0].appendChild(s);void(0)" class="bkl">Planize this</a></p>

  <h2><abbr title="Frequently Asked Questions">FAQ</abbr></h2>
  <dl>
    <dt>Why didn't you use the ordered list feature of the HTML spec?</dt>
    <dd>Because it's lame.</dd>
    
    <dt>Why the hell the code is so ugly?</dt>
    <dd>This is my first jQuery plugin authoring attempt, that's maybe why.</dd>
    
    <dt>Why didn't you use a recursive function to generate TOC subitems code?</dt>
    <dd>Because parsing a linear array of headings and generating a nested list is not that easy, but I can't wait seeing your patch.</dd>
    
    <dt>Can I send you a patch?</dt>
    <dd>Of course, use the <a href="http://code.google.com/p/jqplanize/issues/entry">issue tracker</a> for that purpose.</dd>
    
    <dt>Can I report an issue?</dt>  
    <dd>Of course, use the <a href="http://code.google.com/p/jqplanize/issues/entry">issue tracker</a> for that purpose. Try to attach a patch if you can.</dd>
    
    <dt>Can you grant me a commit access to the subversion repository?</dt>
    <dd>Send me a patch first, if I think it's cool you'll have your commit account.</dd>
  </dl>
  
  <h2>License</h2>
  <p>This plugin is licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>. That means:</p>
  <blockquote>
    <p>Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:</p>

    <p>The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.</p>

    <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.</p>
  </blockquote>

  <h2>About me</h2>
  <p>My name is Nicolas Perriault, I'm a french developer based near Paris. Feel free to <a href="/blog/">browse my blog</a>, mainly in french.</p>
  
  <p id="footer">
    (c) 2008 - <a href="http://prendreuncafe.com/">Nicolas Perriault</a>
  </p>
</body>
</head>